.\" $Id: PAPI_set_debug.3,v 1.10 2004/10/08 11:46:26 mucci Exp $
.TH PAPI_set_debug 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_set_debug \- set the current debug level for PAPI

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_set_debug(int " debuglevel ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_set_debug(C_INT\  debug,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B "PAPI_set_debug" 
sets the debug level for error output from the PAPI library.

.SH ARGUMENTS
.I "debuglevel"
-- one of the constants shown in the table below and defined 
in the papi.h header file.
The current debug level is used by both the internal error and debug message
handler subroutines. The debug handler is only used if the library was compiled
with -DDEBUG. The debug handler is called when there is an error upon a call 
to the PAPI API. The error handler is always active and it's behavior cannot
be modified except for whether or not it prints anything. NOTE: This is
the ONLY function that may be called BEFORE
.B PAPI_library_init().

The PAPI error handler prints out messages in the following form:

PAPI Error: message.

The default PAPI debug handler prints out messages in the following form:

PAPI Error: Error Code code,symbol,description

If the error was caused from a system call and the return code is PAPI_ESYS,
the message will have a colon space and the error string as reported by
strerror() appended to the end.

The possible debug levels for debugging are shown in the table below.
.TS
allbox tab($);
lB l.
PAPI_QUIET$Do not print anything, just return the error code
PAPI_VERB_ECONT$Print error message and continue
PAPI_VERB_ESTOP$Print error message and exit
.TE

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
The debuglevel is invalid.

.SH EXAMPLES
.nf
.if t .ft CW
  if ( PAPI_set_debug(PAPI_VERB_ECONT) != PAPI_OK )
     handle_error();
.if t .ft CW
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_set_opt "(3), "
.BR PAPI_get_opt "(3), "
.BR PAPI_library_init "(3) "

